Skip to content

Clarify local server lifecycle help - #561

Merged
sdairs merged 3 commits into
stack/476-fix-start-help-quotesfrom
stack/478-lifecycle-help
Aug 27, 2026
Merged

Clarify local server lifecycle help#561
sdairs merged 3 commits into
stack/476-fix-start-help-quotesfrom
stack/478-lifecycle-help

Conversation

@sdairs

@sdairs sdairs commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • document exact-current-directory lifecycle scope and current stop/remove omission rules
  • add the canonical named workflow, generated-name retention, and project cleanup guidance
  • contrast installed-version removal with named server-data removal in CLI help and README
  • pin rendered lifecycle help and README removal guidance with exact tests
  • keep the mandated project-cleanup recommendation in agent help while trimming duplicate README and subcommand wording

Tests

  • cargo test -p clickhousectl local::cli::tests::server_help_pins_scope_workflow_and_removal_distinction
  • cargo test -p clickhousectl local::cli::tests::readme_contrasts_version_and_server_removal
  • cargo fmt --all --check
  • cargo clippy -p clickhousectl --all-targets -- -D warnings
  • cargo check -p clickhousectl
  • cargo test -p clickhousectl local::cli::tests::server_ (13 passed; 2 pre-existing assertion/help-text mismatches remain outside the authenticated review scope)

Closes #478

@sdairs

sdairs commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator Author

Carry-over review from PR #520 (old PR for #478). This PR is substantively stronger than #520: stop-selection wording fixed to match the actual code (mod.rs:~896-927), scope sentence consistently worded on every subcommand, removal contrast present in CLI help as well as README, and exact-block assert_eq! pinning instead of #520's substring contains(). All six acceptance criteria met. But it re-adds content sdairs explicitly trimmed on #520. Required:

  1. Reconcile with sdairs' two trim comments on Clarify local server lifecycle help #520 (both re-violated here). On Clarify local server lifecycle help #520, sdairs left two pending review comments, then self-addressed them in commit c764b48 ("Trim local lifecycle help"):

    • Comment 1 (cli.rs): "no need to explain obvious commands that adds nothing over the command descriptor". The trim removed the top-level sentence restating stop-all's descriptor. This PR re-adds that class of content in three places: cli.rs:~313-314 ("For project cleanup, use clickhousectl local server stop-all."), cli.rs:~450 ("Use clickhousectl local server stop-all when the intent is project cleanup."), and README.md:~293. Mitigation: issue Clarify local server lifecycle help: CWD scope, omitted-name behavior, and agent workflow #478 criterion 4 explicitly requires "Help recommends server stop-all when the intent is project cleanup", so the guidance is mandated. A reviewer applying comment 1's standard could still flag the wording as restating the descriptor — either trim to the minimal mandated form or state in the PR description that the earlier trim is being consciously relaxed to satisfy the acceptance criterion.
    • Comment 2 (README.md): "this is a readme, not agent help. this does not need to be added here". The trim removed the generated-name operational reminder from the README. This PR re-adds it nearly verbatim at README.md:~300: "Retain the returned generated name for later stop and remove commands, or pass a name positionally for a stable identity." The CLI help already carries this (cli.rs:~347). Delete the README retain-clause (or justify the reversal explicitly).
  2. Note: the scope sentence is now duplicated verbatim 6 times (group + start/list/stop/stop-all/remove). Any wording change breaks 6 places — acceptable for agent-facing help, but be aware.

  3. CI note: local postgres edge cases fails here; docs-only diff, so this is inherited from the stack base (Validate local Postgres start options #547 script drift). Confirm resolved after that lands and the stack rebases.

Supersede/close #520 when this merges to avoid duplicate "Closes #478".

@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 2a1b601 to c917d4e Compare August 26, 2026 18:58
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from c917d4e to 9355c3d Compare August 26, 2026 19:01
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch 3 times, most recently from fbe3d48 to e092ce6 Compare August 26, 2026 19:10
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from e092ce6 to 99ef1c2 Compare August 26, 2026 19:12
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 99ef1c2 to 5a67b3d Compare August 26, 2026 19:20
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 5a67b3d to ade0543 Compare August 26, 2026 19:24
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from ade0543 to 3c09690 Compare August 26, 2026 19:28
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 3c09690 to 94e5a6e Compare August 26, 2026 19:31
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 94e5a6e to 7bdd691 Compare August 26, 2026 19:34
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 7bdd691 to 0bc7268 Compare August 26, 2026 19:36
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch 2 times, most recently from 1ceb29d to 4c18155 Compare August 26, 2026 20:30
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from cb3861f to 2525917 Compare August 27, 2026 06:49
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 2525917 to 416012c Compare August 27, 2026 06:53
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 416012c to c36f301 Compare August 27, 2026 06:57
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from c36f301 to 027a532 Compare August 27, 2026 07:06
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch 2 times, most recently from 9659a72 to 76ce33e Compare August 27, 2026 07:17
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 76ce33e to 5eaf45f Compare August 27, 2026 07:24

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 5eaf45f. Configure here.

Comment thread crates/clickhousectl/src/local/cli.rs
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 5eaf45f to ac2bf5f Compare August 27, 2026 07:32
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from ac2bf5f to 617ff8f Compare August 27, 2026 07:37
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 1f65be5 to 4b10f08 Compare August 27, 2026 09:19
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 4b10f08 to 95d9976 Compare August 27, 2026 10:13
@sdairs
sdairs force-pushed the stack/478-lifecycle-help branch from 95d9976 to 2d3c511 Compare August 27, 2026 10:51
@sdairs
sdairs merged commit 4211ece into main Aug 27, 2026
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify local server lifecycle help: CWD scope, omitted-name behavior, and agent workflow

2 participants